<html>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<head>
<title>Section 7.9.&nbsp; Environment Variables</title>
<link rel="STYLESHEET" type="text/css" href="images/style.css">
<link rel="STYLESHEET" type="text/css" href="images/docsafari.css">
</head>
<body>
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tr><td><div STYLE="MARGIN-LEFT: 0.15in;"><a href="toc.html"><img src="images/team.gif" width="60" height="17" border="0" align="absmiddle"  alt="Team BBL"></a></div></td>
<td align="right"><div STYLE="MARGIN-LEFT: 0.15in;">
<a href=ch07lev1sec8.html><img src="images/prev.gif" width="60" height="17" border="0" align="absmiddle" alt="Previous Page"></a>
<a href=ch07lev1sec10.html><img src="images/next.gif" width="60" height="17" border="0" align="absmiddle" alt="Next Page"></a>
</div></td></tr></table>
<br><table width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td valign="top"><a name="ch07lev1sec9"></a>
<h3 class="docSection1Title">7.9. Environment Variables</h3>
<p class="docText">As we mentioned earlier, the environment strings are usually of the form</P>
<blockquote>
<p class="docText"><span class="docEmphasis">name</span><tt>=</tt><span class="docEmphasis">value</span></P>
</blockquote>
<p class="docText">The UNIX kernel never looks at these strings; their interpretation is up to the various applications. The shells, for example, use numerous environment variables. Some, such as <tt>HOME</tt> and <tt>USER</tt>, are set automatically at login, and others are for us to set. We normally set environment variables in a shell start-up file to control the shell's actions. If we set the environment variable <tt>MAILPATH</tt>, for example, it tells the Bourne shell, GNU Bourne-again shell, and Korn shell where to look for mail.</p>
<p class="docText">ISO C defines a function that we can use to fetch values from the environment, but this standard says that the contents of the environment are implementation defined.</P>
<a name="inta99"></a><P><table cellspacing="0" class="allBorders" border="1" RULES="none" cellpadding="5"><colgroup><col width="500"></colgroup><thead></thead><TR><td class="docTableCell" align="left" valign="top"><p class="docText">
<pre>
#include &lt;stdlib.h&gt;

char *getenv(const char *<span class="docEmphItalicAlt">name</span>);
</pre><BR>

</P></TD></tr><TR><td class="docTableCell" align="right" valign="top"><p class="docText">Returns: pointer to <span class="docEmphasis">value</span> associated with <span class="docEmphasis">name</span>, <tt>NULL</tt> if not found</P></TD></TR></table></p><BR>
<p class="docText"><a name="idd1e48742"></a><a name="idd1e48747"></a><a name="idd1e48752"></a><a name="idd1e48757"></a><a name="idd1e48762"></a><a name="idd1e48767"></a><a name="idd1e48773"></a><a name="idd1e48779"></a><a name="idd1e48785"></a><a name="idd1e48791"></a><a name="idd1e48797"></a><a name="idd1e48803"></a><a name="idd1e48809"></a><a name="idd1e48815"></a><a name="idd1e48821"></a><a name="idd1e48827"></a><a name="idd1e48833"></a><a name="idd1e48839"></a><a name="idd1e48845"></a><a name="idd1e48851"></a><a name="idd1e48857"></a><a name="idd1e48863"></a><a name="idd1e48869"></a><a name="idd1e48875"></a><a name="idd1e48881"></a><a name="idd1e48887"></a><a name="idd1e48892"></a><a name="idd1e48895"></a><a name="idd1e48900"></a><a name="idd1e48903"></a><a name="idd1e48908"></a><a name="idd1e48913"></a><a name="idd1e48918"></a><a name="idd1e48923"></a><a name="idd1e48928"></a><a name="idd1e48933"></a><a name="idd1e48938"></a><a name="idd1e48943"></a><a name="idd1e48948"></a><a name="idd1e48951"></a><a name="idd1e48954"></a><a name="idd1e48959"></a><a name="idd1e48962"></a><a name="idd1e48967"></a><a name="idd1e48972"></a><a name="idd1e48977"></a><a name="idd1e48982"></a><a name="idd1e48987"></a><a name="idd1e48990"></a><a name="idd1e48993"></a><a name="idd1e48998"></a><a name="idd1e49003"></a><a name="idd1e49008"></a><a name="idd1e49011"></a>Note that this function returns a pointer to the <span class="docEmphasis">value</span> of a <span class="docEmphasis">name=value</span> string. We should always use <tt>getenv</tt> to fetch a specific value from the environment, instead of accessing <tt>environ</tt> directly.</P>
<p class="docText">Some environment variables are defined by POSIX.1 in the Single UNIX Specification, whereas others are defined only if the XSI extensions are supported. <a class="docLink" href="#ch07fig07">Figure 7.7</a> lists the environment variables defined by the Single UNIX Specification and also notes which implementations support the variables. Any environment variable defined by POSIX.1 is marked with &#8226;; otherwise, it is an XSI extension. Many additional implementation-dependent environment variables are used in the four implementations described in this book. Note that ISO C doesn't define any environment variables.</p>
<a name="ch07fig07"></a><P><table cellspacing="0" class="allBorders" border="1" RULES="groups" cellpadding="5"><caption><H5 class="docTableTitle">Figure 7.7. Environment variables defined in the Single UNIX Specification</h5></caption><colgroup><col width="100"><col width="40"><col width="40"><col width="40"><col width="60"><col width="50"><col width="170"></colgroup><thead><tr><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="middle"><p class="docText"><span class="docEmphRoman">Variable</span></p></th><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="middle"><p class="docText"><span class="docEmphRoman">POSIX.1</span></p></th><th class="bottomBorder thead" scope="col" align="center" valign="bottom"><p class="docText"><span class="docEmphRoman">FreeBSD 5.2.1</span></P></th><th class="bottomBorder thead" scope="col" align="center" valign="bottom"><p class="docText"><span class="docEmphRoman">Linux 2.4.22</span></p></th><th class="bottomBorder thead" scope="col" align="center" valign="bottom"><p class="docText"><span class="docEmphRoman">Mac OS X 10.3</span></P></th><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="bottom"><p class="docText"><span class="docEmphRoman">Solaris 9</span></p></th><th class="bottomBorder thead" scope="col" align="center" valign="middle"><p class="docText"><span class="docEmphRoman">Description</span></P></th></tr></thead><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>COLUMNS</tt></p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="left" valign="top"><p class="docText">terminal width</P></TD></tr><TR><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>DATEMSK</tt></P></td><TD class="rightBorder" align="center" valign="top"><p class="docText">XSI</p></TD><TD class="docTableCell" align="center" valign="top">&nbsp;</TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="docTableCell" align="center" valign="top">&nbsp;</TD><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="left" valign="top"><p class="docText"><tt>getdate</tt>(3) template file pathname</P></td></TR><tr><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>HOME</tt></p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><TD class="docTableCell" align="left" valign="top"><p class="docText">home directory</P></td></TR><TR><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>LANG</tt></p></TD><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><td class="docTableCell" align="left" valign="top"><p class="docText">name of locale</p></td></TR><tr><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>LC_ALL</tt></p></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="left" valign="top"><p class="docText">name of locale</p></TD></TR><tr><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>LC_COLLATE</tt></P></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="left" valign="top"><p class="docText">name of locale for collation</p></td></tr><tr><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>LC_CTYPE</tt></p></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="left" valign="top"><p class="docText">name of locale for character classification</p></td></tr><TR><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>LC_MESSAGES</tt></p></TD><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="docTableCell" align="left" valign="top"><p class="docText">name of locale for messages</P></TD></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>LC_MONETARY</tt></p></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="left" valign="top"><p class="docText">name of locale for monetary editing</p></td></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>LC_NUMERIC</tt></P></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="left" valign="top"><p class="docText">name of locale for numeric editing</P></td></TR><TR><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>LC_TIME</tt></p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="left" valign="top"><p class="docText">name of locale for date/time formatting</p></td></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>LINES</tt></p></td><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="left" valign="top"><p class="docText">terminal height</p></TD></TR><tr><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>LOGNAME</tt></P></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="left" valign="top"><p class="docText">login name</p></td></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>MSGVERB</tt></p></td><td class="rightBorder" align="center" valign="top"><p class="docText">XSI</p></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="center" valign="top">&nbsp;</TD><td class="docTableCell" align="center" valign="top">&nbsp;</TD><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="left" valign="top"><p class="docText"><tt>fmtmsg</tt>(3) message components to process</p></TD></TR><TR><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>NLSPATH</tt></P></TD><td class="rightBorder" align="center" valign="top"><p class="docText">XSI</P></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="left" valign="top"><p class="docText">sequence of templates for message catalogs</p></td></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>PATH</tt></p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="left" valign="top"><p class="docText">list of path prefixes to search for executable file</p></TD></tr><TR><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>PWD</tt></P></td><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><td class="docTableCell" align="left" valign="top"><p class="docText">absolute pathname of current working directory</p></td></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>SHELL</tt></p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="left" valign="top"><p class="docText">name of user's preferred shell</P></TD></tr><TR><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>TERM</tt></P></TD><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="left" valign="top"><p class="docText">terminal type</p></td></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>TMPDIR</tt></p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="left" valign="top"><p class="docText">pathname of directory for creating temporary files</p></TD></TR><TR><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>TZ</tt></P></td><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="left" valign="top"><p class="docText">time zone information</p></TD></tr></table></p><br>
<p class="docText">In addition to fetching the value of an environment variable, sometimes we may want to set an environment variable. We may want to change the value of an existing variable or add a new variable to the environment. (In the next chapter, we'll see that we can affect the environment of only the current process and any child processes that we invoke. We cannot affect the environment of the parent process, which is often a shell. Nevertheless, it is still useful to be able to modify the environment list.) Unfortunately, not all systems support this capability. <a class="docLink" href="#ch07fig08">Figure 7.8</a> shows the functions that are supported by the various standards and implementations.</p>
<a name="ch07fig08"></a><p><table cellspacing="0" class="allBorders" border="1" RULES="groups" cellpadding="5"><caption><h5 class="docTableTitle">Figure 7.8. Support for various environment list functions</h5></caption><colgroup><col width="100"><col width="50"><col width="50"><col width="50"><col width="50"><col width="60"><col width="40"></colgroup><thead><tr><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="middle"><p class="docText"><span class="docEmphRoman">Function</span></p></th><th class="bottomBorder thead" scope="col" align="center" valign="middle"><p class="docText"><span class="docEmphRoman">ISO C</span></p></th><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="middle"><p class="docText"><span class="docEmphRoman">POSIX.1</span></p></th><th class="bottomBorder thead" scope="col" align="center" valign="bottom"><p class="docText"><span class="docEmphRoman">FreeBSD 5.2.1</span></p></th><th class="bottomBorder thead" scope="col" align="center" valign="bottom"><p class="docText"><span class="docEmphRoman">Linux 2.4.22</span></p></th><th class="bottomBorder thead" scope="col" align="center" valign="bottom"><p class="docText"><span class="docEmphRoman">Mac OS X 10.3</span></p></th><th class="bottomBorder thead" scope="col" align="center" valign="bottom"><p class="docText"><span class="docEmphRoman">Solaris 9</span></p></th></tr></thead><tr><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>getenv</tt></P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD></TR><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>putenv</tt></p></td><TD class="docTableCell" align="center" valign="top">&nbsp;</td><TD class="rightBorder" align="center" valign="top"><p class="docText">XSI</p></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>setenv</tt></p></td><TD class="docTableCell" align="center" valign="top">&nbsp;</TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><TD class="docTableCell" align="center" valign="top">&nbsp;</TD></tr><TR><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>unsetenv</tt></p></TD><TD class="docTableCell" align="center" valign="top">&nbsp;</td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top">&nbsp;</td></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>clearenv</tt></p></td><td class="docTableCell" align="center" valign="top">&nbsp;</td><td class="rightBorder" align="center" valign="top">&nbsp;</td><td class="docTableCell" align="center" valign="top">&nbsp;</td><TD class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="docTableCell" align="center" valign="top">&nbsp;</TD><TD class="docTableCell" align="center" valign="top">&nbsp;</td></TR></table></P><BR>
<blockquote>
<p class="docText"><a name="idd1e49978"></a><a name="idd1e49983"></a><a name="idd1e49988"></a><a name="idd1e49995"></a><a name="idd1e50000"></a><a name="idd1e50007"></a><a name="idd1e50012"></a><tt>clearenv</tt> is not part of the Single UNIX Specification. It is used to remove all entries from the environment list.</p>
</blockquote>
<p class="docText">The prototypes for the middle three functions listed in <a class="docLink" href="#ch07fig08">Figure 7.8</a> are</P>
<a name="inta256"></a><p><table cellspacing="0" class="allBorders" border="1" RULES="none" cellpadding="5"><colgroup><col width="550"></colgroup><thead></thead><TR><TD class="docTableCell" align="left" valign="top"><p class="docText">
<a name="PLID1"></a><div class="v1"><a href="ch07lev1sec9.html#PLID1">[View full width]</a></div><pre>
  #include &lt;stdlib.h&gt;

  int putenv(char *<span class="docEmphItalicAlt">str</span>);

  int setenv(const char *<span class="docEmphItalicAlt">name</span>, const char *<span class="docEmphItalicAlt">value</span>,
<img border="0" width="14" height="9" alt="" align="left" src="images/ccc.gif"> int <span class="docEmphItalicAlt">rewrite</span>);

  int unsetenv(const char *<span class="docEmphItalicAlt">name</span>);
</pre><BR>

</p></TD></TR><tr><TD class="docTableCell" align="right" valign="top"><p class="docText">All return: 0 if OK, nonzero on error</P></td></tr></table></p><br>
<p class="docText">The operation of these three functions is as follows.</P>
<ul><LI><p class="docList">The <tt>putenv</tt> function takes a string of the form <span class="docEmphasis">name=value</span> and places it in the environment list. If <span class="docEmphasis">name</span> already exists, its old definition is first removed.</p></LI><li><p class="docList">The <tt>setenv</tt> function sets <span class="docEmphasis">name</span> to <span class="docEmphasis">value</span>. If <span class="docEmphasis">name</span> already exists in the environment, then (a) if <span class="docEmphasis">rewrite</span> is nonzero, the existing definition for <span class="docEmphasis">name</span> is first removed; (b) if <span class="docEmphasis">rewrite</span> is 0, an existing definition for <span class="docEmphasis">name</span> is not removed, <span class="docEmphasis">name</span> is not set to the new <span class="docEmphasis">value</span>, and no error occurs.</p></li><li><p class="docList">The <tt>unsetenv</tt> function removes any definition of <span class="docEmphasis">name</span>. It is not an error if such a definition does not exist.</p><blockquote><p><p class="docList">Note the difference between <tt>putenv</tt> and <tt>setenv</tt>. Whereas <tt>setenv</tt> must allocate memory to create the <span class="docEmphasis">name=value</span> string from its arguments, <tt>putenv</tt> is free to place the string passed to it directly into the environment. Indeed, on Linux and Solaris, the <tt>putenv</tt> implementation places the address of the string we pass to it directly into the environment list. In this case, it would be an error to pass it a string allocated on the stack, since the memory would be reused after we return from the current function.</p></p></blockquote></li></ul>
<p class="docText">It is interesting to examine how these functions must operate when modifying the environment list. Recall <a class="docLink" href="ch07lev1sec6.html#ch07fig06">Figure 7.6</a>: the environment listthe array of pointers to the actual <span class="docEmphasis">name=value</span> stringsand the environment strings are typically stored at the top of a process's memory space, above the stack. Deleting a string is simple; we simply find the pointer in the environment list and move all subsequent pointers down one. But adding a string or modifying an existing string is more difficult. The space at the <a name="idd1e50175"></a><a name="idd1e50180"></a><a name="idd1e50183"></a><a name="idd1e50188"></a><a name="idd1e50193"></a><a name="idd1e50196"></a><a name="idd1e50201"></a>top of the stack cannot be expanded, because it is often at the top of the address space of the process and so can't expand upward; it can't be expanded downward, because all the stack frames below it can't be moved.</p>
<div style="font-weight:bold"><ol class="docList" type="1"><li><div style="font-weight:normal"><p class="docList">If we're modifying an existing <span class="docEmphasis">name:</span></p><div style="font-weight:bold"><ol class="docList" type="a"><li><div style="font-weight:normal"><p class="docList">If the size of the new <span class="docEmphasis">value</span> is less than or equal to the size of the existing <span class="docEmphasis">value</span>, we can just copy the new string over the old string.</p></div></li><li><div style="font-weight:normal"><p class="docList">If the size of the new <span class="docEmphasis">value</span> is larger than the old one, however, we must <tt>malloc</tt> to obtain room for the new string, copy the new string to this area, and then replace the old pointer in the environment list for <span class="docEmphasis">name</span> with the pointer to this allocated area.</P></div></LI></ol></div></div></li><LI><div style="font-weight:normal"><p class="docList">If we're adding a new <span class="docEmphasis">name</span>, it's more complicated. First, we have to call <tt>malloc</tt> to allocate room for the <span class="docEmphasis">name=value</span> string and copy the string to this area.</P><div style="font-weight:bold"><ol class="docList" type="a"><LI><div style="font-weight:normal"><p class="docList">Then, if it's the first time we've added a new <span class="docEmphasis">name</span>, we have to call <tt>malloc</tt> to obtain room for a new list of pointers. We copy the old environment list to this new area and store a pointer to the <span class="docEmphasis">name=value</span> string at the end of this list of pointers. We also store a null pointer at the end of this list, of course. Finally, we set <tt>environ</tt> to point to this new list of pointers. Note from <a class="docLink" href="ch07lev1sec6.html#ch07fig06">Figure 7.6</a> that if the original environment list was contained above the top of the stack, as is common, then we have moved this list of pointers to the heap. But most of the pointers in this list still point to <span class="docEmphasis">name=value</span> strings above the top of the stack.</p></div></LI><LI><div style="font-weight:normal"><p class="docList">If this isn't the first time we've added new strings to the environment list, then we know that we've already allocated room for the list on the heap, so we just call <tt>realloc</tt> to allocate room for one more pointer. The pointer to the new <span class="docEmphasis">name=value</span> string is stored at the end of the list (on top of the previous null pointer), followed by a null pointer.</P></div></li></ol></div></div></LI></ol></div>

<a href="17021535.html"><img src="images/pixel.gif" alt="" width="1" height="1" border="0"></a><ul></UL></TD></TR></table>
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tr><td><div STYLE="MARGIN-LEFT: 0.15in;"><a href="toc.html"><img src="images/team.gif" width="60" height="17" border="0" align="absmiddle"  alt="Team BBL"></a></div></td>
<td align="right"><div STYLE="MARGIN-LEFT: 0.15in;">
<a href=ch07lev1sec8.html><img src="images/prev.gif" width="60" height="17" border="0" align="absmiddle" alt="Previous Page"></a>
<a href=ch07lev1sec10.html><img src="images/next.gif" width="60" height="17" border="0" align="absmiddle" alt="Next Page"></a>
</div></td></tr></table>
</body></html><br>
<table width="100%" cellspacing="0" cellpadding="0"
style="margin-top: 0pt; border-collapse: collapse;"> 
<tr> <td align="right" style="background-color=white; border-top: 1px solid gray;"> 
<a href="http://www.zipghost.com/" target="_blank" style="font-family: Tahoma, Verdana;
 font-size: 11px; text-decoration: none;">The CHM file was converted to HTM by Trial version of <b>ChmD<!--25-->ecompiler</b>.</a>
</TD>
</TR><tr>
<td align="right" style="background-color=white; "> 
<a href="http://www.etextwizard.com/download/cd/cdsetup.exe" target="_blank" style="font-family: Tahoma, Verdana;
 font-size: 11px; text-decoration: none;">Download <b>ChmDec<!--25-->ompiler</b> at: http://www.zipghost.com</a>
</TD></tr></table>
